home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr42 / vat041.zip / README.TXT < prev    next >
Text File  |  1995-03-19  |  16KB  |  422 lines
  1.                             VARMINT'S AUDIO TOOLS
  2.                              VERSION 0.41  (beta)
  3.  
  4.                       Sound Blaster programming library
  5.  
  6. DISCLAIMER
  7.  
  8.   This software and documentation is provided as-is and is not
  9.   garanteed to do or be anything.  Use at your own risk.
  10.  
  11. INTRODUCTION
  12.  
  13.   Varmint's Audio Tools (VAT) is a small Sound Blaster programming Kit.
  14.   It's primary feature is a DSP interrupt driven core that handles
  15.   real-time mixing and playing of digital sounds and background MIDI
  16.   music.   It also supports many FM chip routines and input functions
  17.   for WAVE samples and MIDI music files.  Auto recognition and setup
  18.   of Sound Blaster compatable cards. 4.5 (adjustable) millisecond clock and
  19.   microsecond accuracy timers. VAT is Freeware and comes with source
  20.   and example code (Turbo C).
  21.  
  22.   VAT was adapted from Peter Sprenger's SoundX library.  Peter's library
  23.   was the only sound blaster library that I could actually get working
  24.   out of the half dozen or so that I ftp'ed from x2ftp.oulu.fi.  It is
  25.   a pretty nice library, but the documentation is lacking and the code
  26.   still has a few flaws, so I decided to find out how it worked and
  27.   then modify it to fit my needs as a novice Sound Blaster Programmer.
  28.   Peter has given me personal permission to distribute this library and
  29.   I want to offer  my special thanks to him for his effort and the
  30.   information he has provided.
  31.  
  32. SO WHO NEEDS IT?
  33.  
  34.   VAT is intended for any programmer who wants to add sound effects
  35.   and music to their programs quickly and easily.  
  36.   Like so many other programmers, I've been very dissappointed by the
  37.   sound library offerings out there.  I have designed VAT to be very easy
  38.   to use and as versatile as possible, and I hope that it is useful to you.
  39.  
  40.   When dealing with routines that run inthe background, most programmers
  41.   are concerned about how many CPU processing cycles the routines use up.  
  42.   Here are the numbers that I get on my 486 DX2/66:
  43.  
  44.   Base overhead:  1.5 %
  45.   Midi overhead:  1.0 % (average)
  46.   Sample overhead: 1.35% per sample
  47.  
  48.   So, let's say that your program is playing some midi music and 4 digital
  49.   samples in the background.  The total overhead would be: 1.5% (base) +
  50.   1% (midi) + 4 * 1.35% (samples) = 7.9%.  That means that
  51.   if you were animating some graphics at 30 FPS, it would slow down to
  52.   27.6 FPS.  Pretty acceptable.
  53.  
  54.  
  55. BETA VERSION
  56.  
  57.   This is the beta version of VAT, so it is a little scant on
  58.   documentation, but I have tried to make up for that by commenting
  59.   the code heavily and providing an example program.
  60.  
  61. HOW TO CONTACT THE AUTHOR(S)
  62.  
  63.   Any suggestions or bug reports are very welcome.  (I've included the
  64.   file "survey.txt" to make this process easier you.) Please send them
  65.   to one of these email addresses:
  66.  
  67.             smeagol@rt66.com
  68.             ejorgensen@rr5.intel.com
  69.  
  70.   Peter Sprenger can be reached at:
  71.  
  72.             Pete@amber.dinoco.de
  73.  
  74.  
  75. FREEWARE
  76.  
  77.   VAT is freeware, so you are free to copy and distribute this library
  78.   as much as you like as long as you charge no fee for it's distribution.
  79.   You are NOT restricted, however, from charging money for games or
  80.   other programs that use VAT to produce sound. All I ask is that you send
  81.   me a complimentary copy.  (Peter Sprenger would like one too.)  This
  82.   helps me as a developer to know who is using my software and for
  83.   what.  It is also a good way to make friends!
  84.  
  85.   In other words:
  86.  
  87.     Q: Can put any of the programs or example code from VAT into my
  88.        own shareware that I am going to sell for money?
  89.  
  90.     A: Absolutely not.
  91.  
  92.     Q: If I use VAT to generate sounds in my game, can I sell my game
  93.        for money?
  94.  
  95.     A: Yes!  (Please send Eric Jorgensen and Peter Sprenger complimentary
  96.        copies of your game!)
  97.  
  98. FEATURES
  99.  
  100.   - Background DMA digital playback with real time mixing and
  101.     unlimited channels.
  102.   - Background Playing of MIDI music with easy control of tempo and volume.
  103.   - Routines to access the FM chip.
  104.   - 4.5 millisecond (adjustable) clock plus microsecond accuracy timers.
  105.   - AUto recognition and setup of Sound Blaster or Sound Blaster
  106.     compatable sound cards.
  107.   - Does not disturb the system clock (does not use int08)
  108.   - Comes with heavily commented source code and demo.
  109.   - Comes with an FM voice editor
  110.  
  111. VARMINT'S HOME FTP SITE
  112.  
  113.   I have a home site for all of my software:
  114.  
  115.       mack.rt66.com:/users/smeagol
  116.  
  117.   Here you can find my other shareware and freeware offerings:
  118.  
  119.     tmkr11.zip          Terrain Maker - A random Terrain generator/
  120.                         editor for the freeware raytracer Persistence
  121.                         of Vision (POV).
  122.  
  123.     vpova10.zip          Varmint's POV animator - A POV scene file parser
  124.                         that allows the inclusion of functions and
  125.                         animation commands.
  126.  
  127.     svgadiag.zip        Free SVGA diagnostic utility
  128.  
  129.     survey_results.txt  Compiled results of a large survey of SVGA cards
  130.                         that I performed in December of 1994.
  131.  
  132. -----------------------------<*>----------------------------------------
  133.  
  134. VOICEED.EXE  - The FM voice editor
  135.  
  136.   This is a simple package to make editing FM voices a little easier
  137.   for you.  To use it, you will need a VGA capable graphics card and a mouse.
  138.   The interface is fairly simple and should be self-explanatory. Here is
  139.   some lame, rudimentary documentation:
  140.  
  141.   To change the name of a voice or a filename, just click on the text and
  142.   the program will let you type in a new name.
  143.  
  144.   To toggle a radio button, just click on it.
  145.  
  146.   To operate a slider, either click and drag the slider tool with the mouse
  147.   or click on the arrows on the sides.  (The arrows move the slider one
  148.   unit.)
  149.  
  150.   Highlighted letters on butons are hot keys.  A button can be accessed
  151.   from the keyboard by pressing the hotkey letter.
  152.  
  153.   Be sure to save the file before you quit the program!
  154.  
  155.  
  156.   More documentation will show up in version 1.0.
  157.  
  158.  
  159. -----------------------------<*>----------------------------------------
  160.  
  161.  
  162.  
  163. USING VARMINT'S AUDIO TOOLS:  A CRASH COURSE
  164.  
  165.   Compiling the source code:
  166.  
  167.     The sound routines are desinged around FAR or HUGE pointers, so
  168.     you need to compile under a large or huge memory model.  If you
  169.     are using Turbo C and you wnat more memore under the debugger,
  170.     you can request more by selecting "Debugger" from the options menu.
  171.  
  172.   Starting up the interrupt core:
  173.  
  174.     #include "sound.h"
  175.  
  176.     main()
  177.     {
  178.       if(SB_Setup()) {
  179.         Go_Varmint();                // THis starts up the background handler
  180.                                     // and enables you to play sounds and
  181.                                     // MIDI music.
  182.         do_some_stuff();
  183.  
  184.         Dropdead_Varmint();          // THis removes Varmint's interrupt and
  185.                                     // puts the regular system clock
  186.                                     // interrupt back.
  187.       }
  188.       else {
  189.         printf("You don't have a sound Blaster.  EGAD!");
  190.       }
  191.     }
  192.  
  193.     ***  IMPORTANT ******  IMPORTANT ******  IMPORTANT ******  IMPORTANT ***
  194.  
  195.     - Do not call Go_Varmint() if SB_Setup() fails.
  196.  
  197.     - If you call Go_Varmint() and your program breaks or crashes before
  198.     Dropdead_Varmint() is called, you should reboot your computer, or
  199.     you might get a system crash next time you run your program.
  200.  
  201.     - If you call Go_Varmint(), you MUST call Dropdead_Varmint() before
  202.     your program exits.  If you don't, you might not be able to run
  203.     your program again without rebooting the system.
  204.  
  205.     - As a general rule, you should only have one Go_Varmint and one
  206.     Dropdead_Varmint() in your code.
  207.  
  208.     ***  IMPORTANT ******  IMPORTANT ******  IMPORTANT ******  IMPORTANT ***
  209.  
  210.  
  211.   Playing Sounds
  212.  
  213.     Once Go_Varmint has been called, you are free to play sounds.  You will
  214.     first need to load the sound (11 Khz, 8bit mono WAVE format.) and stick
  215.     it onto a type HUGE pointer.  
  216.  
  217.     (You can use the function SetRate() to change the playback rate of the
  218.     sounds.  See information about the global variables vlcok and 
  219.     dma_bufferlen below.)
  220.  
  221.     void somefunc()
  222.     {
  223.       unsigned char huge *sounddata;
  224.       unsigned long int sound_length;
  225.  
  226.       sounddata = loadwave("shwoop.wav",&sound_length);
  227.       if(!sounddata) {
  228.         printf("Error loading wave.");
  229.         exit(0);
  230.       }
  231.  
  232.       playsound(sounddata,sound_length);
  233.     }
  234.  
  235.     You only have to load the sound once, and since playsound() handles 
  236.     things intelligently, you can call playsound()
  237.     as many times with as many different samples as you want without  
  238.     having to worry about conflicts. 
  239.     
  240.     playsound() will not cause any problems if Go_Varmint() has not 
  241.     been called, but it won't play anything, either. :)
  242.  
  243.   Playing MIDI files
  244.  
  245.     To play a midi file, you don't actually call a funtion, but you
  246.     instead set values to a few global variables.
  247.  
  248.     unsigned char  inst[1][11] = { 0x03,0x01,0x80,0x80,0xF7,0xF7,
  249.                                   0x13,0x13,0x02,0x01,0x03},  // Harpsichord
  250.  
  251.     void mididemo(void)
  252.     {
  253.       int i,j,k,err;
  254.       char *errstring[256],r=0;
  255.       static MIDI *bach  = NULL;
  256.  
  257.       FM_Reset();
  258.  
  259.       for(i = 0 ; i < 9; i++) {           // Set up FM voices
  260.         FM_SetVol(i,0);
  261.         FM_SetVoice ( i,inst[0]) ;
  262.       }
  263.  
  264.                                           // load a midi file
  265.       err = ReadMidi("bach.mid",&bach,errstring);
  266.       if(err) {
  267.         printf("MIDI read ERROR: %s\n",errstring);
  268.         printf("Exit?\n");
  269.         r = getch();
  270.         if(r != 'n') exit(1);
  271.       }
  272.  
  273.       midi_data = bach;                   // assign the music
  274.       midi_reset = TRUE;                  // reset internal midi variables
  275.       midi_on = TRUE;                      // Turn on the midi player now!
  276.     }
  277.  
  278.     You can adjust the volume by changing the value of the global
  279.     variable "music_volume". (Min = 0, max = 63, default = 50)
  280.  
  281.     You can adjust the tempo by changing the value of the global
  282.     variable "midi_usertempo".  (default = 2.0,  0 = fastest
  283.     50.0 = come back wednesday) See also information about dma_bufferlen
  284.     and midi_tempoadjust below.
  285.  
  286.     Voices can be altered while a song is playing without any problems.
  287.  
  288.  
  289.   Miscellaneous Functions and Variables
  290.  
  291.     extern unsigned _stklen          
  292.       I was getting random reports with older version of the library
  293.       of stack overflow errors and system crashes.  I turned on the stack
  294.       checking option on my compiler, and what do you know, the sound
  295.       code started crashing!  I traced the problem to sb_int().  It only
  296.       crashes when it tries to call external functions.  By all appearances,
  297.       I should only need about 1K of stack space, but I had to increase 
  298.       it to 8K to make the problem go away.  If you can explain this
  299.       behavior, by all means, drop me a note!
  300.  
  301.     void SetRate(int rate)
  302.       This function allows you to dynamically change the playback rate.
  303.       Changing setrate will affect the frequency at which vclock is
  304.       incremented.  It will also affect the midi playback tempo.
  305.  
  306.     long int vclock
  307.       This isn't a function.  It is a global varibable that contains
  308.       the current clock tick from the sound handler.  The frequency
  309.       at which is incremented can be calculated like this:
  310.  
  311.           sample_rate / dma_bufferlen
  312.  
  313.       With library default settings, this is every 5.45 milliseconds.
  314.  
  315.     long int dma_bufferlen
  316.       This is another global variable, and it controls the size of
  317.       the DMA mixing buffer.  The default is 60 bytes.  If you want to 
  318.       change this number, you should do so before you call SB_Setup()
  319.       By making this number bigger, you will lower the frequency that
  320.       sb_int is called.  You might want to do this if you think the sound
  321.       routines are messing up some other time sensitive functions 
  322.       those that look for the VGA verticle sync.
  323.  
  324.       If you increase dma_bufferlen, bbe sure to increase midi_tempoadjust 
  325.       by the same ratio, or your midi flies will play at the wrong speed.
  326.  
  327.     float midi_tempoadjust
  328.       This global variable changes the midi tempo by reducing the delay time
  329.       between notes.  The default value for this is 2.0. Bigger numbers
  330.       make the music faster.  You should only have to mess with this number
  331.       if you cahnge the value of dma_bufferlen.
  332.  
  333.     WORD DSP_overhead
  334.       This is another global variable.  It always holds the number of
  335.       clock ticks that elapsed during the most previous sound handler
  336.       interrupt.  To get the overhead ratio, divide this number by 6000.
  337.  
  338.     void timer_on()
  339.     WORD timer_off()
  340.       This a hyperaccurate suit of timer funcs.  Start by calling
  341.       timer_on() and the read the result from timer_off().  Each tick
  342.       is about 0.838 *micro*seconds.  These functions are only good
  343.       for measuring times shorter than about 50 milliseconds.
  344.  
  345.     msdelay(int milliseconds)
  346.       Standard millisecond delay function.  I mention this becasue VAT
  347.       seems to cause problems with the delay() function included with
  348.       Turbo C.
  349.  
  350.     void load_instruments(char *filename,BYTE inst[128][11])
  351.       This loads 128 instruments definitions from a file of your choosing.
  352.  
  353.     void freemidi(MIDI *m)
  354.       I added this function for convenience.  It automatically frees 
  355.       the a midi structure and the tracks inside it.
  356.  
  357.   A FEW WORDS ABOUT MIDI
  358.  
  359.     The MIDI standard specifies that a midi compliant instument needs to
  360.     have something like 24 voices available for playback.  Since the
  361.     Sound blaster FM chip only offers 9 (even less if you implement
  362.     percussion), You should be wary of playing midi files that play more
  363.     than 9 voices simultaneously.  Here are some general tips:
  364.  
  365.       - use midi files that have only 5-6 voices max.
  366.  
  367.       - Unless you implement rythm voices, chop off the rythm track
  368.         with a midi editor.
  369.  
  370. COMING SOON
  371.  
  372.   Better docs!
  373.  
  374.   New functions!  
  375.     MOD support
  376.     OPL MIDI ouput
  377.  
  378.   Cooler Demo!
  379.  
  380.  
  381.  
  382. -----------------------------<*>----------------------------------------
  383.  
  384.  
  385.  
  386. Here is a note from Peter Sprenger's SoundX library: ------------------
  387.  
  388.                  Pete@amber.dinoco.de
  389.  
  390.  
  391. Why I made this library: I was myself in a search of a good library
  392. for soundblaster programming. What I encountered was the SBF, that
  393. was a nice idea but written in a such a hurry, that it was still
  394. useless. I has still bugs, too. Some other packages looked
  395. interesting but are quite expensive. I just bought the original SBK
  396. from Creative Labs and was disappointed. It was expensive and bad!
  397. In their design I lost control of Timer 0, that I needed for my other
  398. programming.
  399. So I decided to make a good freeware soundblaster bibleothek. Up to
  400. now I spent about 200 hours working time in this project. It is my
  401. hope that their will be other people who make freeware that can be
  402. used. If every programmer would spend about 100 hours for freeware in
  403. the lifetime, not everybody had to reinvent the wheel again. Look at
  404. the guys from GNU and OSF they are doing a great job!
  405.  
  406. If you can use this routines use them! There must be non false shame.
  407. I wrote this stuff that not everybody has to write his own routines.
  408. But it would be nice, that when you make something commercial with my
  409. routines, that you send me a copy of your project or send me some bucks,
  410. just enough for pizza and coke to support my night programming sessions.
  411. If you send me nothing, ok. But USE the stuff, if you can need it!
  412.  
  413. Have fun with SoundX,
  414.  
  415.       Pete
  416.  
  417. Germany, 27-Jun-93
  418.  
  419. ------------------------------------------------------------------------
  420.  
  421.  
  422.